\documentclass[]{article}
\oddsidemargin 0.0in
\evensidemargin 0.0in
\textwidth 6.5in
\topmargin 0.0in
\textheight 9.0in


\usepackage{amsmath,amssymb,amsfonts,amstext} % extended math symbols etc
\usepackage{graphicx}% Include figure files
\usepackage{bm}% bold math

\newcommand{\code}[1]{{\tt #1}}
\newcommand{\shell}[1]{\begin{tabular}{r||l}&\code{#1} \end{tabular}}

% For some unknown reason definitions like \PETSCDIR, when used in the text, eat the immediately following space.
% This necessitates usage like "\PETSCDIR\ and \PETSCARCH, which " etc.  
% Once I figure out how to uneat the space, the usage will become simpler.  Sorry.
\newcommand{\PETSCDIR}{{\code{\$\{PETSC\_DIR\}}}}
\newcommand{\petscdir}{{$\langle$\emph{petsc\_dir}$\rangle$}}
\newcommand{\PETSCARCH}{{\code{\$\{PETSC\_ARCH\}}}}
\newcommand{\petscarch}{{$\langle$\emph{petsc\_arch}$\rangle$}}
\newcommand{\dftfftarch}{\code{dft\_fft\_arch}}
\newcommand{\DFTFFTDIR}{{\code{\$\{DFT\_FFT\_DIR\}}}}
\newcommand{\dftfftdir}{{$\langle$\emph{dft\_fft\_dir}$\rangle$}}
\newcommand{\NUMSPECIES}{{\code{\$\{NUM\_SPECIES\}}}}
\newcommand{\numspecies}{{$\langle$\emph{num\_species}$\rangle$}}
\newcommand{\EX}{{\code{\$\{EX\}}}}
\newcommand{\ex}{{$\langle$\emph{ex}$\rangle$}}




\newcommand{\C}{\mathbb{C}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\Z}{\mathbb{Z}}

\newcommand{\vecj}{\Vec{j}}
\newcommand{\veck}{\Vec{k}}
\newcommand{\vecr}{\Vec{r}}
\newcommand{\vecx}{\Vec{x}}
\newcommand{\vecy}{\Vec{y}}

% hyperref package should always be loaded as the very last one
% to be sure that it has the last word ...
\usepackage[
  pdftex,
  pdftitle={DFT-FFT: User's Manual},
  pdfauthor={Dmitry~A. Karpeev, Matthew~G. Knepley},
  pdfpagemode={UseOutlines},
  bookmarks, bookmarksopen,bookmarksnumbered={True},
  colorlinks, linkcolor={blue},citecolor={blue},urlcolor={blue}
]{hyperref}

\renewcommand{\baselinestretch}{2}

\begin{document}

\title{DFT-FFT: A Density Functional code for Hard Sphere Charged Liquids in 1D and 3D.\\User's manual.}
\author{
Dmitry~A. Karpeev\footnote{Mathematics and Computer Science Division, Argonne National Laboratory, {\tt
    karpeev@mcs.anl.gov}},\quad
Matthew~G. Knepley\footnote{Computation Institute, University of Chicago, {\tt knepley@ci.uchicago.edu}}
}
\date{\today}
\maketitle
\section{Installing DFT-FFT}
\subsection{Installing PETSc.}
DFT-FFT relies on PETSc (Portable Extensible Toolking for Scientific Computation)
\cite{petsc-web-page} for many of its internal needs.  Most importantly,
DFT-FFT is built on top of PETSc and uses its build system to compile the DFT-FFT 
library.  Building applications and other libraries on top of DFT-FFT will naturally require
PETSc's libraries and header files, in addition to DFT-FFT's libraries and headers.  
Therefore, before proceeding any further with DFT-FFT, PETSc has to be built.
Once that has been done, we provide build commands to compile the DFT-FFT library
and supply a template \code{makefile} that can be used to compile codes built on top of DFT-FFT.  
This makefile will automatically supply the information about both PETSc and DFT-FFT header
files to the compiler, as well as the corresponding library information to the linker.


\subsubsection{Where to find help installing and using PETSc.}
For detailed instruction on downloading, installing and using PETSc see \cite{petsc-user-ref}.
When in doubt or questions arise, do not hesitate to email {\tt petsc-maint@mcs.anl.gov}
for help.  In most cases related to the installation and building of PETSc 
you will need to attach \code{configure.log} to allow the PETSc maintenance team to 
determine the nature of the problem you are experiencing.  However, just about any question
concerning the usage of PETSc can be answered by writing to {\tt petsc-maint@mcs.anl.gov}.

\subsubsection{Important environment variables: \PETSCDIR\ and \PETSCARCH.}
Once PETSc has been downloaded, it resides in the directory that we will designate throughout
this manual by \petscdir.  This directory path must be stored in environment variable \PETSCDIR,\ which 
is used extensively by the PETSc build system and the DFT-FFT build system.  This variable 
can be defined automatically upon login by setting it in \emph{\~\,/.bashrc, \~\,/.bash\_profile, \~\,/.cshrc} 
or the equivalent shell \emph{resource file} for the particular shell you are using.  Alternatively, it can be set 
``manually'' from the command line.  In the \emph{bash} shell this is done as follows:\\
\shell{export PETSC\_DIR=\petscdir}


PETSc comes with its own \texttt{configure} system, which determines the 
\emph{architecture} -- the software configuration of the system.  The determined architecture is
named using the user-supplied label \petscarch.  This happens during the configuration process
by giving \code{configure} argument \code{--PETSC\_ARCH=\petscarch} (see \cite{petsc-user-ref}
for more details).  The architecture name, stored the \PETSCARCH\ environment variable is then used
to build PETSc and place the compiled libraries in an appropriate location.

{\bf Remark:} The term \emph{architecture} in \PETSCARCH\ does \emph{not} refer to the underlying hardware architecture.
It is a term designating the combination of compilers and libraries used to build PETSc.  A more appropriate
term may be \emph{configuration}.  For the moment we are stuck with \emph{architecture} and \emph{arch} for historic
reasons.

DFT-FFT makes extensive use of \PETSCDIR\ and \PETSCARCH\ environment variables and they have to be defined in 
any shell in which DFT-FFT is being built, either by defining them in the shell resource file, directly on the 
command line or even immediately within the command used to build DFT-FFT as in the following example:\\
\shell{make PETSC\_DIR=\petscdir\ PETSC\_ARCH=\petscarch}\\
The same applies to building codes based on DFT-FFT
that are compiled using the DFT-FFT build system (e.g., a \code{makefile} derived from the supplied template).

{\bf Remark:} In addition to the build and installation process based on \PETSCDIR\ and \PETSCARCH, PETSc also supports
the GNU-style installation with the \code{--prefix} configure option.  DFT-FFT does not work with such PETSc 
installations because it needs to access the appropriate pieces of the PETSc build system defined by \PETSCDIR\ and 
\PETSCARCH.

{\bf Summary:} Define \PETSCDIR=\petscdir\ \PETSCARCH=\petscarch\ with the values \petscdir\ and \petscarch\ used while
configuring PETSc.  These variables are used by DFT-FFT build commands described later in this manual.


\subsubsection{Cofiguring and building PETSc for use with DFT-FFT.}
PETSc's user manual \cite{petsc-user-ref} describes how to configure PETSc to use an appropriate set of compilers, 
libraries and to enable a set of various desirable features.  DFT-FFT requires several spefic PETSc features:
the use of complex arithmetic and the use of FFT (Fast Fourier Transform) libraries.  Currently (as of version 3.0.0)
PETSc only supports a serial version of the FFTW (Fastest Fourier Transform in the West) library \cite{fftw-web-page}.
The use of complex arithmetic necessitates the use of a C++ compiler to build PETSc.  The following PETSc 
configuration command is virtually\footnote{PETSc configuration and building can be somewhat challenging on some 
operating systems, notably, Windows and MacOS.  This has nothing to do with DFT-FFT as such.  Please, email 
\code{petsc-maint@mcs.anl.gov} with your \code{configure.log} if problems arise.} guaranteed to produce 
a \code{PETSC\_ARCH}, denoted \dftfftarch\ throughout this manual, suitable for DFT-FFT.
While in \petscdir\ with and \PETSCDIR=\petscdir\ execute:\\
\shell{./configure --PETSC\_ARCH=\dftfftarch\ --clanguage=c++ --with-scalar-type=complex $\backslash$}\\
\shell{            --download-fftw --download-mpich --download-c-blas-lapack}\\
Once \code{configure} completes successfully, compile PETSc as follows:\\
\shell{make PETSC\_ARCH=\dftfftarch}

\subsection{Building DFT-FFT.}
Once PETSc has been built DFT-FFT can be compiled.  Similar to \PETSCDIR, 
enviroment variable \DFTFFTDIR defines the location \dftfftdir of the DFT-FFT code.
With all three variables defined as described above, the library can be compiled.  
For example, with \dftfftdir as the current 
directory:\\
\shell{make \PETSCDIR=\petscdir \PETSCARCH=\dftfftarch \DFTFFTDIR=\dftfftdir}\\
Likewise, using bash:\\
\shell{export \PETSCDIR=\petscdir}\\
\shell{export \PETSCARCH=\dftfftarch}\\
\shell{export \DFTFFTDIR=\dftfftdir}\\
\shell{cd \dftfftdir}\\
\shell{make}

\subsection{Compiling with a given number of species.}
Currently, DFT-FFT hardcodes the number of species for efficiency reasons.
This limits the usefulness of the library to some extent, since two instances
of \code{DFT} cannot be used with different numbers of species.  This constraint
may be relaxed in the future.  For now, the number of species can be specified at
compile time using environment variable \NUMSPECIES, which must be a positive integer.
For example,\\
\shell{cd \dftfftdir}\\
\shell{make \PETSCDIR=\petscdir \PETSCARCH=\dftfftarch \DFTFFTDIR=\dftfftdir \NUMSPECIES=3}\\
will compile the library for 3 species and place it in \code{\dftfftdir/lib/\dftfftarch/3}.
The default is \NUMSPECIES=2.  There is no need to know the precise location of the compiled
library, if using \code{makefile} provided with DFT-FFT, because it is defined as a variable there.
This makefile is used, for example, to compile tests, as described in Section~\ref{sec:building-tests}.
In general, the currently used number of species will be denoted \numspecies throughout this manual.

\subsection{Building tests and examples.\label{sec:building-tests}}
Some simple test drivers that use the DFT-FFT library are located in \code{\dftfftdir/tests}.
To build \code{simpleTest}, for example, the following sequence of commands can be used:\\
\shell{cd \dftfftdir/tests}\\
\shell{make PETSC\_DIR=\petscdir PETSC\_ARCH=\dftfftarch DFT\_FFT\_DIR=\dftfftdir \NUMSPECIES=\numspecies EX=simpleTest}\\
As always, the environment variables used above can be defined in a shell resource file or elsewhere,
so long as they have appropriate values in the current shell.  In that case, the following simpler commands can be
used:\\
\shell{cd \DFTFFTDIR/tests}\\
\shell{make EX=simpleTest}\\
Here \EX holds the name of the test executable being built.  Currently \code{simpleTest} is the only one available, 
but the number of tests will grow in the nearest future. The general build command is:\\
\shell{make EX=\ex}\\
where \ex is the name of the desired test executable.
The above command will generate executable \EX in \code{\DFTFFTDIR/tests/\PETSCARCH/\NUMSPECIES}.
Naturally, the DFT-FFT library has to be built with the corresponding value of \NUMSPECIES for the compilation of \EX 
to succeed.  

\subsection{Understanding test \code{makefile}.}
In order to understand how the executable is built and placed, it is useful to examine
\code{\DFTFFTDIR/tests/makefile}.


\section{Useful literature.}
The density functional theory of charged hard spheres is described in some detail in 
\cite{GillespieNonnerEisenberg02}.  In particular, the 1D hard sphere excess chemical potential implementation
follows that publication down to its notation.
\newpage
\bibliographystyle{plain}
\bibliography{dft-fft}

\end{document}
